home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 22
/
Cream of the Crop 22.iso
/
bbs
/
sm103.zip
/
CGIMAIL.TXT
< prev
next >
Wrap
Text File
|
1996-07-29
|
9KB
|
305 lines
Stalker's CGIMail V1.03 07.29.96 / Eric Voisard
====================================================
Copyright (c) Stalker Lab (SaRL), Switzerland
All Rights Reserved.
S T A L K E R SaRL
Jaquet-Droz 18
2300 La Chaux-de-Fonds
Switzerland
phone: +41 39 225 666
fax: +41 39 225 667
email: tech@cdf.globalcafe.ch (soon: tech@stalker.ch)
Stalker's CGIMail is freeware and can be freely distributed.
The Software is provided on an "AS IS" basis, without warranty of any
kind. Eric Voisard and Stalker Lab declines any responsability in the
eventuality of damages caused by the use of this software.
1. INTRODUCTION
---------------
Stalker's CGIMail as says its self-explanatory name, is a CGI program
allowing a http server to send SMTP mail with data coming from a HTML
form.
As a 32bits app, it requires Microsoft Windows 95 or (better)
Windows NT.
2. FEATURES
-----------
The mail is based on template text files with variables in it, and
stored in the server. When launched, Stalker's CGIMail loads a
specified template, replaces the variables with data coming from
HTML form, before to send the resulting text as mail body.
Stalker's CGIMail allows multiple "To", "Cc" and "Bcc" recipients, and
is MIME compliant (useful for countries other than US!).
3. INSTALLATION
---------------
Stalker's CGIMail.exe must be installed in a CGI mapped directory on
the server (not a winCGI one!). CGImail.ini must be in the same
directory. Mail templates may be in other directories.
4. CALLING THE CGI
------------------
As a CGI 1.1. specs compliant program, Stalker's CGIMail is called
with the POST method, like:
<form method=POST action="/cgi-bin/CGIMail.exe">
5. VARIABLES
------------
Variables are user defined and Stalker's CGIMail allows up to 1000 of
them. They are words bracketed within '$' chars (e.g. $var$), they can
be up to 32 chars long including '$'s. Variables are case sensitive,
spaces are allowed but their use is discouraged.
The names must be the same in the HTML form and in the templates.
Stalker's CGIMail routine tries to find as many matches as it can
between form names and templates variables, and replaces all what it
can with form values.
In example, HTML lines like these:
<ol>
<li><input type="radio" name="$var1$" value="I'm born to run UNIX">
I work on UNIX.
<li><input type="radio" name="$var1$" value="NT is a good OS" checked>
I work on NT.
</ol>
With a template line like this:
Hi, I think $var1$! That's all what I have to say.
Will give:
Hi, I think NT is a good OS! That's all what I have to say.
Or:
Hi, I think I'm born to run UNIX! That's all what I have to say.
An unique variable name can be used several times in the template, it
will be replaced as many times as it appears.
Note that if a template variable was not passed by form, it is not
treated and is sent "as is" in the mail.
If a form field doesn't have any matches in the template, it is
ignored.
6. RESERVED VARIABLES
---------------------
Some variables are reserved words for internal use. Some are not
needed, others must be specified in the form. They are:
$File$ NEEDED!
Name and pathname of the template to be used with the current form.
(! If no local path is specified, CGImail will check in its directory)
$LocationOK$ NEEDED!
The URL to go if mail is correctly sent.
(! If no URL path is specified, CGImail will check in its directory)
$LocationKO$ NEEDED!
The URL to go if an error has occured and mail is not sent.
(! If no URL path is specified, CGImail will check in its directory)
$Subject$ Not needed
Subject of the mail which appears in the mail header.
$Sender$ Not needed
Overrides sender's address of CGImail.ini (see CGImail.ini).
$Realname$ Not needed
Overrides sender's real name of CGImail.ini (see CGImail.ini).
$Optional$ Not needed
For optionally passed values from form (see below).
$To$ At least ONE IS NEEDED
A normal "To:" mail recipient.
$Cc$ Not needed
A "Carbon-copy" mail recipient.
$Bcc$ Not needed
A "Blind Carbon-copy" mail recipient.
User can specifie more than one $To$, $Cc$ and $Bcc$ recipients in the
form, but not more than 100 recipients at all.
These variables (and others) will not appear on the client's browser
if "hidden" is specified in the HTML form source.
7. OPTIONAL VALUES
------------------
Some of the name/value pairs on the form are not necessary passed to
the CGI by the httpd. In example, an unchecked checkbox will neither
send a value, nor its referencing name.
This causes garbage in the resulting message because the CGI does not
find any match for corresponding template variable, and send it "as is"
in the mail.
To allow the use of such optional values, the reserved variable
$Optional$ can be specified in the form, with a default value string.
In the template and the form, a prefix "Opt." must be appended in the
concerned variables names (e.g. $Opt.MyCheckBox$).
Then, if the CGI find the $Optional$ reserved variable, it will replace
all remaining $Opt.<name>$ variables with the default value string.
Usually, a NULL string will be used as default string.
8. TEMPLATES FILES
------------------
Templates are simple texts that can be edited with the Windows Notepad
in example. Since Stalker's CGIMail is MIME compliant, extended chars
and charsets other than 7 bits US-Ascii can be used.
There is no limit with the file size, but each line can't be longer
than 1000 chars and MUST be ended with CR/LF (Carriage-Return and
Line-Feed). Note that UNIX style (LF alone) will work, but Macintosh
type (CR alone) will not.
Templates can be stored anywhere in the Web server, but paths (local
paths!) must be specified within the $File$ form variable.
9. CGIMail.ini
--------------
Some setting must be specified in the .ini file:
Gateway=
Name of the SMTP relay
Sender=
Email address of the sender which will appear in the "From:" field of
the mail header. An idea is to set the webmaster's one, so if the mail
bounces, he is informed.
Realname=
Real name of the sender which will also appear in the "From:" field of
the mail header. Can be used to specify that mail comes from a CGI.
MIMEncode=
This is a MIME encoding parameter. Stalker's CGIMail uses MIME specs
declarations and encoding.
If MIMEncode=no, mail will be sent 8bits MIME to the mail relay
without encoding.
If MIMEncode=yes, mail will be sent 7bits Quoted-printable MIME
encoded. This setting depends on the mail relay capabilities to handle
8bits chars, but it is more reliable to force 7bits encoding.
Charset=
Specifies the local charset used (e.g. US = us-ascii; Latin =
iso-8859-1)
10. LOGGING THE PROCESS
----------------------
Each time Stalker's CGIMail is called, it creates or overwrites
CGIMail.log in the CGIMail.exe directory. All the process and the
dialogs with the SMTP gateway are stored in this file. This is useful
for debugging when errors occur or just to verify the process.
11. WHEN AN ERROR OCCURS
------------------------
If an error occurs, the client's browser is redirected to $LocationKO$.
When possible, the error is specified in the log file (it's a good
idea to check it, times to times). If the mail message was present
before the error occured, or if the mail was not or partially sent for
any reason, it is appended to the file dead.letter.txt. So it is
possible to handle it manually as a last resort.
The only error which can't be logged is the CGI unable to handle the
log file! If the CGI can't open the log file, the process is aborted
and the client receive a brief message asking him to inform the
webmaster.
So, if you never receive mail from the CGI, or if errors seems to
occur but nothing is logged, turn around the log file to fix the
problem.
12. REFERENCES
--------------
[1] J. Postel,
"SMTP (Simple Mail Transfert Protocol)", RFC 821, ISI, August 1982
[2] Crocker, D.,
"Standard for the Format of ARPA Internet Text Messages", STD 11,
RFC 822, UDEL, August 1982.
[3] Borenstein N., and N. Freed
"MIME (Multipurpose Internet Mail Extensions)
Part One: Mechanismsfor Specifying and Describing the Format of
Internet Message Bodies", RFC 1521, Bellcore, Innosoft, September 1993.
[4] K. Moore
"MIME (Multipurpose Internet Mail Extensions)
Part Two: Message Header Extensions for Non-ASCII Text", RFC 1522,
University of Tennessee, September 1993.
[5] D.R.T Robinson
"The WWW Common Gateway Interface Version 1.1", IETF Internet-Draft,
University of Cambridge, 15 February 1996
13. HISTORY
-----------
07.29.96 Version 1.03
-Added internal variables to override sender's address and real name
of CGImail.ini.
-Added a date stamp on messages appended to dead.letter.txt for better
management.
07.24.96 Version 1.02
-Improved the MIME conversion routine.
-Added optional form values handling.
07.10.96 Version 1.01
-Fixed minor bug causing inappropriate error message.
-Changed a test causing the sending (RCPT TO) of recipient list
to be stopped a first incorrect one, and mail to be unsent to
remaining correct recipients. Now, all valid recipients will
receive their mail.
07.02.96 Version 1.00
-First release